home *** CD-ROM | disk | FTP | other *** search
/ Personal Computer World 2009 February / PCWFEB09.iso / Software / Linux / SLAX 6.0.8 / slax-6.0.8.iso / slax / base / 006-devel.lzm / usr / include / isccfg / cfg.h < prev    next >
Encoding:
C/C++ Source or Header  |  2008-09-17  |  10.5 KB  |  418 lines
  1. /*
  2.  * Copyright (C) 2004-2006  Internet Systems Consortium, Inc. ("ISC")
  3.  * Copyright (C) 2000-2002  Internet Software Consortium.
  4.  *
  5.  * Permission to use, copy, modify, and distribute this software for any
  6.  * purpose with or without fee is hereby granted, provided that the above
  7.  * copyright notice and this permission notice appear in all copies.
  8.  *
  9.  * THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
  10.  * REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
  11.  * AND FITNESS.  IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
  12.  * INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
  13.  * LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
  14.  * OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
  15.  * PERFORMANCE OF THIS SOFTWARE.
  16.  */
  17.  
  18. /* $Id: cfg.h,v 1.34.18.5 2006/03/02 00:37:22 marka Exp $ */
  19.  
  20. #ifndef ISCCFG_CFG_H
  21. #define ISCCFG_CFG_H 1
  22.  
  23. /*****
  24.  ***** Module Info
  25.  *****/
  26.  
  27. /*! \file
  28.  * \brief
  29.  * This is the new, table-driven, YACC-free configuration file parser.
  30.  */
  31.  
  32. /***
  33.  *** Imports
  34.  ***/
  35.  
  36. #include <isc/formatcheck.h>
  37. #include <isc/lang.h>
  38. #include <isc/types.h>
  39. #include <isc/list.h>
  40.  
  41.  
  42. /***
  43.  *** Types
  44.  ***/
  45.  
  46. /*%
  47.  * A configuration parser.
  48.  */
  49. typedef struct cfg_parser cfg_parser_t;
  50.  
  51. /*%
  52.  * A configuration type definition object.  There is a single
  53.  * static cfg_type_t object for each data type supported by
  54.  * the configuration parser.
  55.  */
  56. typedef struct cfg_type cfg_type_t;
  57.  
  58. /*%
  59.  * A configuration object.  This is the basic building block of the
  60.  * configuration parse tree.  It contains a value (which may be
  61.  * of one of several types) and information identifying the file
  62.  * and line number the value came from, for printing error
  63.  * messages.
  64.  */
  65. typedef struct cfg_obj cfg_obj_t;
  66.  
  67. /*%
  68.  * A configuration object list element.
  69.  */
  70. typedef struct cfg_listelt cfg_listelt_t;
  71.  
  72. /*%
  73.  * A callback function to be called when parsing an option 
  74.  * that needs to be interpreted at parsing time, like
  75.  * "directory".
  76.  */
  77. typedef isc_result_t
  78. (*cfg_parsecallback_t)(const char *clausename, const cfg_obj_t *obj, void *arg);
  79.  
  80. /***
  81.  *** Functions
  82.  ***/
  83.  
  84. ISC_LANG_BEGINDECLS
  85.  
  86. isc_result_t
  87. cfg_parser_create(isc_mem_t *mctx, isc_log_t *lctx, cfg_parser_t **ret);
  88. /*%<
  89.  * Create a configuration file parser.  Any warning and error
  90.  * messages will be logged to 'lctx'.
  91.  *
  92.  * The parser object returned can be used for a single call
  93.  * to cfg_parse_file() or cfg_parse_buffer().  It must not
  94.  * be reused for parsing multiple files or buffers.
  95.  */
  96.  
  97. void
  98. cfg_parser_setcallback(cfg_parser_t *pctx,
  99.                cfg_parsecallback_t callback,
  100.                void *arg);
  101. /*%<
  102.  * Make the parser call 'callback' whenever it encounters
  103.  * a configuration clause with the callback attribute,
  104.  * passing it the clause name, the clause value,
  105.  * and 'arg' as arguments.
  106.  *
  107.  * To restore the default of not invoking callbacks, pass
  108.  * callback==NULL and arg==NULL.
  109.  */
  110.  
  111. isc_result_t
  112. cfg_parse_file(cfg_parser_t *pctx, const char *filename,
  113.            const cfg_type_t *type, cfg_obj_t **ret);
  114. isc_result_t
  115. cfg_parse_buffer(cfg_parser_t *pctx, isc_buffer_t *buffer,
  116.          const cfg_type_t *type, cfg_obj_t **ret);
  117. /*%<
  118.  * Read a configuration containing data of type 'type'
  119.  * and make '*ret' point to its parse tree.
  120.  *
  121.  * The configuration is read from the file 'filename'
  122.  * (isc_parse_file()) or the buffer 'buffer'
  123.  * (isc_parse_buffer()).
  124.  *
  125.  * Returns an error if the file does not parse correctly.
  126.  * 
  127.  * Requires:
  128.  *\li     "filename" is valid.
  129.  *\li     "mem" is valid.
  130.  *\li    "type" is valid.
  131.  *\li     "cfg" is non-NULL and "*cfg" is NULL.
  132.  *
  133.  * Returns:
  134.  *     \li #ISC_R_SUCCESS                 - success
  135.  *\li      #ISC_R_NOMEMORY                - no memory available
  136.  *\li      #ISC_R_INVALIDFILE             - file doesn't exist or is unreadable
  137.  *\li      others                          - file contains errors
  138.  */
  139.  
  140. void
  141. cfg_parser_destroy(cfg_parser_t **pctxp);
  142. /*%<
  143.  * Destroy a configuration parser.
  144.  */
  145.  
  146. isc_boolean_t
  147. cfg_obj_isvoid(const cfg_obj_t *obj);
  148. /*%<
  149.  * Return true iff 'obj' is of void type (e.g., an optional 
  150.  * value not specified).
  151.  */
  152.  
  153. isc_boolean_t
  154. cfg_obj_ismap(const cfg_obj_t *obj);
  155. /*%<
  156.  * Return true iff 'obj' is of a map type.
  157.  */
  158.  
  159. isc_result_t
  160. cfg_map_get(const cfg_obj_t *mapobj, const char* name, const cfg_obj_t **obj);
  161. /*%<
  162.  * Extract an element from a configuration object, which
  163.  * must be of a map type.
  164.  *
  165.  * Requires:
  166.  * \li     'mapobj' points to a valid configuration object of a map type.
  167.  * \li     'name' points to a null-terminated string.
  168.  * \li    'obj' is non-NULL and '*obj' is NULL.
  169.  *
  170.  * Returns:
  171.  * \li     #ISC_R_SUCCESS                  - success
  172.  * \li     #ISC_R_NOTFOUND                 - name not found in map
  173.  */
  174.  
  175. const cfg_obj_t *
  176. cfg_map_getname(const cfg_obj_t *mapobj);
  177. /*%<
  178.  * Get the name of a named map object, like a server "key" clause.
  179.  *
  180.  * Requires:
  181.  *    \li  'mapobj' points to a valid configuration object of a map type.
  182.  *
  183.  * Returns:
  184.  * \li     A pointer to a configuration object naming the map object,
  185.  *    or NULL if the map object does not have a name.
  186.  */
  187.  
  188. isc_boolean_t
  189. cfg_obj_istuple(const cfg_obj_t *obj);
  190. /*%<
  191.  * Return true iff 'obj' is of a map type.
  192.  */
  193.  
  194. const cfg_obj_t *
  195. cfg_tuple_get(const cfg_obj_t *tupleobj, const char *name);
  196. /*%<
  197.  * Extract an element from a configuration object, which
  198.  * must be of a tuple type.
  199.  *
  200.  * Requires:
  201.  * \li     'tupleobj' points to a valid configuration object of a tuple type.
  202.  * \li     'name' points to a null-terminated string naming one of the
  203.  *\li    fields of said tuple type.
  204.  */
  205.  
  206. isc_boolean_t
  207. cfg_obj_isuint32(const cfg_obj_t *obj);
  208. /*%<
  209.  * Return true iff 'obj' is of integer type.
  210.  */
  211.  
  212. isc_uint32_t
  213. cfg_obj_asuint32(const cfg_obj_t *obj);
  214. /*%<
  215.  * Returns the value of a configuration object of 32-bit integer type.
  216.  *
  217.  * Requires:
  218.  * \li     'obj' points to a valid configuration object of 32-bit integer type.
  219.  *
  220.  * Returns:
  221.  * \li     A 32-bit unsigned integer.
  222.  */
  223.  
  224. isc_boolean_t
  225. cfg_obj_isuint64(const cfg_obj_t *obj);
  226. /*%<
  227.  * Return true iff 'obj' is of integer type.
  228.  */
  229.  
  230. isc_uint64_t
  231. cfg_obj_asuint64(const cfg_obj_t *obj);
  232. /*%<
  233.  * Returns the value of a configuration object of 64-bit integer type.
  234.  *
  235.  * Requires:
  236.  * \li     'obj' points to a valid configuration object of 64-bit integer type.
  237.  *
  238.  * Returns:
  239.  * \li     A 64-bit unsigned integer.
  240.  */
  241.  
  242. isc_boolean_t
  243. cfg_obj_isstring(const cfg_obj_t *obj);
  244. /*%<
  245.  * Return true iff 'obj' is of string type.
  246.  */
  247.  
  248. const char *
  249. cfg_obj_asstring(const cfg_obj_t *obj);
  250. /*%<
  251.  * Returns the value of a configuration object of a string type
  252.  * as a null-terminated string.
  253.  *
  254.  * Requires:
  255.  * \li     'obj' points to a valid configuration object of a string type.
  256.  *
  257.  * Returns:
  258.  * \li     A pointer to a null terminated string.
  259.  */
  260.  
  261. isc_boolean_t
  262. cfg_obj_isboolean(const cfg_obj_t *obj);
  263. /*%<
  264.  * Return true iff 'obj' is of a boolean type.
  265.  */
  266.  
  267. isc_boolean_t
  268. cfg_obj_asboolean(const cfg_obj_t *obj);
  269. /*%<
  270.  * Returns the value of a configuration object of a boolean type.
  271.  *
  272.  * Requires:
  273.  * \li     'obj' points to a valid configuration object of a boolean type.
  274.  *
  275.  * Returns:
  276.  * \li     A boolean value.
  277.  */
  278.  
  279. isc_boolean_t
  280. cfg_obj_issockaddr(const cfg_obj_t *obj);
  281. /*%<
  282.  * Return true iff 'obj' is a socket address.
  283.  */
  284.  
  285. const isc_sockaddr_t *
  286. cfg_obj_assockaddr(const cfg_obj_t *obj);
  287. /*%<
  288.  * Returns the value of a configuration object representing a socket address.
  289.  *
  290.  * Requires:
  291.  * \li     'obj' points to a valid configuration object of a socket address type.
  292.  *
  293.  * Returns:
  294.  * \li     A pointer to a sockaddr.  The sockaddr must be copied by the caller
  295.  *      if necessary.
  296.  */
  297.  
  298. isc_boolean_t
  299. cfg_obj_isnetprefix(const cfg_obj_t *obj);
  300. /*%<
  301.  * Return true iff 'obj' is a network prefix.
  302.  */
  303.  
  304. void
  305. cfg_obj_asnetprefix(const cfg_obj_t *obj, isc_netaddr_t *netaddr,
  306.             unsigned int *prefixlen);
  307. /*%<
  308.  * Gets the value of a configuration object representing a network
  309.  * prefix.  The network address is returned through 'netaddr' and the
  310.  * prefix length in bits through 'prefixlen'.
  311.  *
  312.  * Requires:
  313.  * \li     'obj' points to a valid configuration object of network prefix type.
  314.  *\li    'netaddr' and 'prefixlen' are non-NULL.
  315.  */
  316.  
  317. isc_boolean_t
  318. cfg_obj_islist(const cfg_obj_t *obj);
  319. /*%<
  320.  * Return true iff 'obj' is of list type.
  321.  */
  322.  
  323. const cfg_listelt_t *
  324. cfg_list_first(const cfg_obj_t *obj);
  325. /*%<
  326.  * Returns the first list element in a configuration object of a list type.
  327.  *
  328.  * Requires:
  329.  * \li     'obj' points to a valid configuration object of a list type or NULL.
  330.  *
  331.  * Returns:
  332.  *   \li   A pointer to a cfg_listelt_t representing the first list element,
  333.  *     or NULL if the list is empty or nonexistent.
  334.  */
  335.  
  336. const cfg_listelt_t *
  337. cfg_list_next(const cfg_listelt_t *elt);
  338. /*%<
  339.  * Returns the next element of a list of configuration objects.
  340.  *
  341.  * Requires:
  342.  * \li     'elt' points to cfg_listelt_t obtained from cfg_list_first() or
  343.  *    a previous call to cfg_list_next().
  344.  *
  345.  * Returns:
  346.  * \li     A pointer to a cfg_listelt_t representing the next element,
  347.  *     or NULL if there are no more elements.
  348.  */
  349.  
  350. const cfg_obj_t *
  351. cfg_listelt_value(const cfg_listelt_t *elt);
  352. /*%<
  353.  * Returns the configuration object associated with cfg_listelt_t.
  354.  *
  355.  * Requires:
  356.  * \li     'elt' points to cfg_listelt_t obtained from cfg_list_first() or
  357.  *    cfg_list_next().
  358.  *
  359.  * Returns:
  360.  * \li     A non-NULL pointer to a configuration object.
  361.  */
  362.  
  363. void
  364. cfg_print(const cfg_obj_t *obj,
  365.       void (*f)(void *closure, const char *text, int textlen),
  366.       void *closure);
  367. /*%<
  368.  * Print the configuration object 'obj' by repeatedly calling the
  369.  * function 'f', passing 'closure' and a region of text starting
  370.  * at 'text' and comprising 'textlen' characters.
  371.  */
  372.  
  373. void
  374. cfg_print_grammar(const cfg_type_t *type,
  375.       void (*f)(void *closure, const char *text, int textlen),
  376.       void *closure);
  377. /*%<
  378.  * Print a summary of the grammar of the configuration type 'type'.
  379.  */
  380.  
  381. isc_boolean_t
  382. cfg_obj_istype(const cfg_obj_t *obj, const cfg_type_t *type);
  383. /*%<
  384.  * Return true iff 'obj' is of type 'type'. 
  385.  */
  386.  
  387. void cfg_obj_destroy(cfg_parser_t *pctx, cfg_obj_t **obj);
  388. /*%<
  389.  * Destroy a configuration object.
  390.  */
  391.  
  392. void
  393. cfg_obj_log(const cfg_obj_t *obj, isc_log_t *lctx, int level,
  394.             const char *fmt, ...)
  395.     ISC_FORMAT_PRINTF(4, 5);
  396. /*%<
  397.  * Log a message concerning configuration object 'obj' to the logging
  398.  * channel of 'pctx', at log level 'level'.  The message will be prefixed
  399.  * with the file name(s) and line number where 'obj' was defined.
  400.  */
  401.  
  402. const char *
  403. cfg_obj_file(const cfg_obj_t *obj);
  404. /*%<
  405.  * Return the file that defined this object.
  406.  */
  407.  
  408. unsigned int
  409. cfg_obj_line(const cfg_obj_t *obj);
  410. /*%<
  411.  * Return the line in file where this object was defined.
  412.  */
  413.  
  414.  
  415. ISC_LANG_ENDDECLS
  416.  
  417. #endif /* ISCCFG_CFG_H */
  418.